docs: clarify --artifact-type=docker requires registry digest by AlexKantor87 · Pull Request #834 · kosli-dev/cli

AlexKantor87 · 2026-04-28T13:50:52Z

Summary

A customer hit Error: repo digest unavailable for the image, has it been pushed to or pulled from a registry? after running kosli attest artifact ... --artifact-type=docker in CI, where the image was built but never pushed. Locally the same command appeared to work because the image had been pulled earlier and the digest was cached on the machine.

The constraint that --artifact-type=docker needs a registry-resident image was only stated in the error message itself. The long descriptions of every attest command (via fingerprintDesc) and kosli fingerprint describe the four artifact types but don't surface this requirement.

This PR adds a Note: paragraph to:

fingerprintDesc in cmd/kosli/root.go — flows into the long help of attest artifact, attest generic, attest snyk, attest sonar, attest junit, attest jira, attest custom, and the PR-attest commands.
fingerprintLongDesc in cmd/kosli/fingerprint.go — kosli fingerprint directly.

The note covers the registry requirement and points at --artifact-type=oci and --artifact-type=dir as alternatives.

Out of scope

Not changing the short flag description (artifactTypeFlag constant) — it's terse on purpose and shows in many help screens. The detail belongs in the long description.

Test plan

make build passes
go vet ./cmd/kosli/... passes
kosli attest artifact --help shows the new note
kosli fingerprint --help shows the new note
CI lint and integration tests pass
After merge + next release, the auto-generated client_reference/kosli_attest_artifact.md in kosli-dev/docs will pick this up via the update-cli-docs workflow

🤖 Generated with Claude Code

claude · 2026-04-28T13:51:41Z

Claude finished @mbevc1's task in 2m 28s —— View job

PR Review: docs: clarify --artifact-type=docker requires registry digest

Run static analysis (build, vet, mod tidy)
Review changed files
Check for the failing test mentioned by mbevc1
Post review feedback

Static Analysis

All checks pass:

go build ./... — clean
go vet ./... — clean
go mod tidy — no drift

Review

Overall: This looks good. The PR is well-scoped — it adds documentation for a real customer pain point without changing any runtime behavior. The two approved reviews and mbevc1's test-data fix (commits 413507b0 and 8c9410a5) have addressed the CI failure.

What I checked:

Consistency — The note in root.go (fingerprintDesc) and fingerprint.go (fingerprintLongDesc) convey the same information. The fingerprint.go version is a bit more concise, which makes sense since that constant already has surrounding context about docker/registry fingerprinting. Both follow the existing ^…^ caret-marker convention for inline code in help text.
Test data — cmd/kosli/testdata/output/docs/mintlify/artifact.md correctly uses backticks (the rendered form of ^ markers) and matches the expected output for the docs generation test. mbevc1's fix commits have this aligned.
Scope — The fingerprintDesc constant flows into all attest commands and the fingerprint command. No other test data files reference this text, so no additional golden files need updating.
Trailing whitespace fix — The diff also cleans up a trailing space on line 45 of root.go (flag, or → flag, or). Minor but welcome.

No bugs, security issues, or missing edge cases — this is a pure documentation change. LGTM.

A customer hit "repo digest unavailable for the image, has it been pushed to or pulled from a registry?" after kosli attest artifact with --artifact-type=docker in CI, where the image was built but never pushed. The constraint that the docker artifact type requires a registry-resident image was only stated in the error itself. Add a note to the long descriptions of attest commands (via fingerprintDesc) and kosli fingerprint, covering the constraint and pointing at oci and dir as alternatives. Help-text only; no behaviour change. Auto-generated docs in kosli-dev/docs will pick this up on the next CLI release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Source-dir fingerprinting only works as an end-to-end identity if the runtime side also fingerprints the source dir. Standard Kosli runtime reporters fingerprint the running image, so suggesting dir as a generic swap is misleading — the attested and running artifacts would never link. Push and oci are the safe answers for the typical case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mbevc1 · 2026-04-28T16:36:09Z

Failing test, cmd/kosli/testdata/output/docs/mintlify/artifact.md needs updating as well. Adding a fix!

#834) * docs: clarify --artifact-type=docker requires registry digest A customer hit "repo digest unavailable for the image, has it been pushed to or pulled from a registry?" after kosli attest artifact with --artifact-type=docker in CI, where the image was built but never pushed. The constraint that the docker artifact type requires a registry-resident image was only stated in the error itself. Add a note to the long descriptions of attest commands (via fingerprintDesc) and kosli fingerprint, covering the constraint and pointing at oci and dir as alternatives. Help-text only; no behaviour change. Auto-generated docs in kosli-dev/docs will pick this up on the next CLI release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: drop dir suggestion from artifact-type=docker note Source-dir fingerprinting only works as an end-to-end identity if the runtime side also fingerprints the source dir. Standard Kosli runtime reporters fingerprint the running image, so suggesting dir as a generic swap is misleading — the attested and running artifacts would never link. Push and oci are the safe answers for the typical case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AlexKantor87 enabled auto-merge (squash) April 28, 2026 15:33

tooky approved these changes Apr 28, 2026

View reviewed changes

mbevc1 approved these changes Apr 28, 2026

View reviewed changes

AlexKantor87 and others added 2 commits April 28, 2026 17:16

mbevc1 force-pushed the docs/clarify-docker-registry-requirement branch from d13ef90 to 7848fbd Compare April 28, 2026 16:16

mbevc1 added 2 commits April 28, 2026 17:44

fix: align test data for artifact testing

413507b

fix: align test data for artifact testing - replace carets

8c9410a

mbevc1 requested a review from tooky April 28, 2026 17:09

tooky approved these changes Apr 28, 2026

View reviewed changes

AlexKantor87 merged commit 346ca39 into main Apr 28, 2026
20 checks passed

AlexKantor87 deleted the docs/clarify-docker-registry-requirement branch April 28, 2026 18:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: clarify --artifact-type=docker requires registry digest#834

docs: clarify --artifact-type=docker requires registry digest#834
AlexKantor87 merged 4 commits intomainfrom
docs/clarify-docker-registry-requirement

AlexKantor87 commented Apr 28, 2026

Uh oh!

claude Bot commented Apr 28, 2026 •

edited

Loading

Uh oh!

mbevc1 commented Apr 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

AlexKantor87 commented Apr 28, 2026

Summary

Out of scope

Test plan

Uh oh!

claude Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: docs: clarify --artifact-type=docker requires registry digest

Static Analysis

Review

Uh oh!

mbevc1 commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

claude Bot commented Apr 28, 2026 •

edited

Loading

mbevc1 commented Apr 28, 2026 •

edited

Loading